home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / prog / rtmem100.zip / RTMEM.DOC < prev   
Text File  |  1992-01-10  |  13KB  |  306 lines
  1.                                  RTMEM 1.00
  2.  
  3.     Purpose
  4.     -------
  5.     RTMEM (Run-Time MEMory) is a programmer's diagnostic aid that allows
  6.     you to easily run programs with a specific amount of free memory
  7.     available.  It is easier to use than the traditional "memory eaters"
  8.     and more accurate than loading other programs, adjusting BUFFERS,
  9.     etc., simply to take up space.
  10.  
  11.  
  12.     Background
  13.     ----------
  14.     It is not at all uncommon for a program to operate correctly on the
  15.     developer's system but fail on a user's system.  There are many
  16.     possible causes for this situation; one of these is that the user's
  17.     system has a different amount of DOS memory available for the
  18.     program.
  19.  
  20.     The traditional approach to analyzing whether or not this is the
  21.     case is to reduce the developer's system's free memory in one way or
  22.     another, then run the program to see if it fails.  This is typically
  23.     accomplished by loading multiple copies of COMMAND.COM or DEBUG, by
  24.     increasing FILES and/or BUFFERS, by running the program from the
  25.     "shell" option of an application, or by using tools such as Turbo
  26.     Power Software's EATMEM.
  27.  
  28.     The problem with adjusting BUFFERS or loading other programs before
  29.     running the target is that it's hard to "eat" just the right amount
  30.     of memory; and unless you have exactly the right amount of free RAM,
  31.     you may not see the problem.  EATMEM is better, but it has two
  32.     problems.  First, it's still rather coarse (allocations are made in
  33.     units of K-bytes).  Second, it's a TSR.  Once memory has been
  34.     "eaten" by EATMEM, you can't get it back without either rebooting or
  35.     using a TSR manager such as MARK/RELEASE.
  36.  
  37.     RTMEM solves these problems; it allows you to specify the exact
  38.     amount of free memory you want available to the target program, and
  39.     it is not a TSR.  After running the target program, you still have
  40.     all of your original DOS memory free.
  41.  
  42.  
  43.     Use
  44.     ---
  45.     Usage of RTMEM is very simple:
  46.  
  47.         RTMEM memorysize d:\path\name.exe [parameters]
  48.  
  49.     The first argument is the amount of free memory you want available
  50.     to the target program (NOT the amount of memory you want RTMEM to
  51.     "eat").  It is specified in bytes, not KB or paragraphs.  Note,
  52.     however, that DOS allocates memory in units of paragraphs (16
  53.     bytes); RTMEM will round up to the next paragraph if you specify a
  54.     number that is not a multiple of 16 bytes.  For ease of data entry,
  55.     you can include commas in the memory size; RTMEM will ignore them.
  56.  
  57.     The second argument is the fully-qualified name of the program you
  58.     want to run: the drive, path, name and extension.  You can omit the
  59.     drive and/or path only if the program is located in the default
  60.     drive and/or path; RTMEM does not search the system PATH.
  61.  
  62.     Following the program name are any parameters required for operation
  63.     of the program (i.e., the same parameters/options you would use to
  64.     run the program without RTMEM).
  65.  
  66.     Examples:
  67.  
  68.         RTMEM 314992 c:\arf\foo.exe /d /e
  69.  
  70.     This example runs C:\ARF\FOO.EXE with 314,992 bytes of free memory.
  71.     The options "/d /e" are passed along to FOO.EXE.
  72.  
  73.         RTMEM 145,008 c:\dos\mem.exe
  74.  
  75.     This example runs MEM.EXE with 145,008 bytes of free memory.  The
  76.     display from MEM.EXE shows the following when run on our system with
  77.     this command:
  78.  
  79.         655360 bytes total conventional memory
  80.         655360 bytes available to IBM DOS
  81.         145008 largest executable program size      <---
  82.  
  83.     Before running the program, RTMEM displays the segment address at
  84.     which the target program will load:
  85.  
  86.         Target program will load at 7F09
  87.  
  88.     This message indicates that the program will be loaded at segment
  89.     7F09 (hex).  This will be the address of the program's PSP, not of
  90.     its environment.
  91.  
  92.     When the target program terminates, RTMEM regains control and
  93.     returns to DOS, releasing any memory that it has allocated.
  94.  
  95.  
  96.     Environment
  97.     -----------
  98.     The question arises, "what about the system environment?"  Suppose
  99.     a customer reports that your program fails on his system and the
  100.     running MEM indicates 542,496 bytes of free memory.  You can easily
  101.     run
  102.  
  103.         RTMEM 542,496 c:\myprog.exe
  104.  
  105.     But what if your DOS environment is not the same size as your
  106.     customer's?  If your environment is 1K larger than his, doesn't that
  107.     mean that using the same size will actually result in 1K less memory
  108.     available to the program on your system than on his?
  109.  
  110.     In general, the answer is "no," if you are using either MEM or
  111.     CHKDSK to report free memory.  Both of these programs report the
  112.     amount of memory that will be available to run a program AFTER space
  113.     has been allocated for the current environment.  RTMEM also follows
  114.     this convention; in other words, if you tell it to allow X bytes of
  115.     free memory for a program, it assumes you mean X bytes of memory
  116.     free AFTER the new environment has been allocated.  Therefore, use
  117.     the exact number reported by either MEM or CHKDSK when running
  118.     RTMEM.
  119.  
  120.  
  121.     Running under a debugger
  122.     ------------------------
  123.     Once you have determined that memory size is indeed the problem, you
  124.     may need to run the target program (with the correct memory size)
  125.     under a debugger.  The problem is, of course, that the debugger
  126.     takes some memory.
  127.  
  128.     There are several ways to approach this problem.  Here is one:
  129.  
  130.         1. Run RTMEM with no arguments except /L:
  131.  
  132.             RTMEM /L
  133.  
  134.         With /L, RTMEM simply displays its own load address and then
  135.         terminates:
  136.  
  137.             RTMEM is loaded at 0BCB     [for example]
  138.  
  139.         Make a note of this address.
  140.  
  141.         2. Load the target program under your debugger; display the CPU
  142.         registers and make a note of the value contained in the DS
  143.         register.  This is the segment address at which your debugger
  144.         has loaded the target program.  NOTE: use the full path to your
  145.         debugger when you run it; this is necessary to ensure that
  146.         the debugger's environment is the same size it will be when you
  147.         run it under RTMEM later.
  148.  
  149.         3. Subtract the RTMEM /L load address from the DS value.  Since
  150.         the debugger and RTMEM loaded at the same address, the
  151.         difference between DS and the address displayed by RTMEM /L
  152.         represents the size of the debugger (in paragraphs), including
  153.         any memory it has taken for symbol storage, etc.
  154.  
  155.         4. Convert the number calculated in step 3 to decimal, and
  156.         multiply it by 16.  This is the amount of memory consumed by the
  157.         debugger, in bytes.
  158.  
  159.         5. Add the value from step 4 to the desired memory size for the
  160.         target program.
  161.  
  162.         6. Run your debugger under RTMEM, using the value calculated in
  163.         step 5.
  164.  
  165.     For example, suppose you want to run C:\ARF\FOO.EXE under DEBUG with
  166.     135,008 bytes of free memory.  Running:
  167.  
  168.         RTMEM 135008 C:\ARF\FOO.EXE
  169.  
  170.     has confirmed that there is a problem in FOO when this amount of
  171.     memory is available.  The steps above might look like this:
  172.  
  173.         1. Run RTMEM /L:
  174.  
  175.                 C> RTMEM /L
  176.                 RTMEM is loaded at 05D7
  177.  
  178.         2. Run DEBUG:
  179.  
  180.                 C> C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  181.  
  182.            Display the registers:
  183.  
  184.  
  185.                 AX=0000  BX=0000  ...
  186.                 DS=0BCB  ES=0BCB  ...
  187.  
  188.            Note the DS value (0BCB).
  189.  
  190.         3. Subtract the RTMEM /L address from DEBUG's DS:
  191.  
  192.                 0BCB - 05D7 = 05F4
  193.  
  194.            DEBUG is using 05F4 paragraphs of memory.
  195.  
  196.         4. Convert 05F4 to decimal (1524) and multiply by 16; the result
  197.            is 24384, which is the amount of memory DEBUG is using, in
  198.            bytes.
  199.  
  200.         5. Add the result from step 4 to the desired free memory for
  201.            FOO.EXE:
  202.  
  203.                 135008 + 24384 = 159392
  204.  
  205.         6. Run FOO under DEBUG under RTMEM with the value from step 5:
  206.  
  207.                 C> RTMEM 159392 C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  208.  
  209.     FOO should now have 135008 bytes of memory available (159392 less
  210.     the 24384 bytes being used by DEBUG).
  211.  
  212.     To confirm, note the initial value of DS when the target program is
  213.     loaded under your debugger.  This should be the same value displayed
  214.     by RTMEM if you run the target program directly (without the
  215.     debugger) and specify the desired memory size.  In our example:
  216.  
  217.         C> RTMEM 135008 C:\ARF\FOO.EXE
  218.         target program will load at 7F09
  219.         ...
  220.         C> RTMEM 159392 C:\DOS\DEBUG.COM C:\ARF\FOO.EXE
  221.         -R
  222.         AX=0000  BX=0000  ...
  223.         DS=7F09  ES=7F09  ...
  224.  
  225.     Note that the value of DEBUG's DS is the same as the load address
  226.     displayed by RTMEM.
  227.  
  228.  
  229.     Error messages
  230.     --------------
  231.     RTMEM reports the following errors:
  232.  
  233.     requested size greater than available memory
  234.         The memory size you specified on the command line is greater
  235.         than the amount of memory currently available.  RTMEM can only
  236.         decrease free memory, not increase it.
  237.  
  238.     program not found (remember to use path and extension)
  239.         RTMEM was unable to find the target program.  Be sure that you
  240.         have specified everything it needs to find the program: the
  241.         drive (if the program is not on the current drive), the
  242.         directory (if the program is not in the current directory), and
  243.         the program name AND extension.  Do not rely on the PATH.
  244.  
  245.     requested size is not enough to run the program
  246.         RTMEM could not run the target program due to insufficient
  247.         memory; in other words, you executed "RTMEM 50000 foo.exe",
  248.         and FOO.EXE cannot run in 50,000 bytes of memory.
  249.  
  250.     error running program
  251.         Catch-all message for other errors encountered in attempting
  252.         to run the program.  You should not see this message...
  253.  
  254.     memory size specified greater than 1MB
  255.         Just what it says: you specified a memory size larger than 1MB.
  256.  
  257.  
  258.                          COPYRIGHT/LICENSE/WARRANTY
  259.                          --------------------------
  260.  
  261.     This document and the program file RTMEM.COM ("the software") are
  262.  
  263.                              Copyright (C) 1992
  264.                           The Cove Software Group
  265.                             All Rights Reserved
  266.  
  267.     The copyright owner hereby licenses you to: use the software except
  268.     as below; make as many copies of the program and documentation as
  269.     you wish; give such copies to anyone; and distribute the software
  270.     and documentation via electronic means.  There is no charge for any
  271.     of the above.
  272.  
  273.     You are specifically prohibited from charging, or requesting
  274.     donations, for any such copies, however made; and from distributing
  275.     the software and/or documentation with commercial products without
  276.     prior permission in writing from the copyright owner.
  277.  
  278.     Persons and organizations who are engaged in the distribution of
  279.     shareware, "freeware", and/or public domain software may include RTMEM
  280.     on distribution disks as long as charges are made on a per-disk
  281.     basis rather than a per-program basis.  The charge per disk may not
  282.     exceed $7 US.  Such persons and organizations must not represent
  283.     themselves as vendors, distributors, or sellers of RTMEM.
  284.  
  285.     RTMEM may not be used in a commercial, governmental, or institutional
  286.     environment.  It is intended for personal use only.  Other users
  287.     should contact us for licensing information.
  288.  
  289.     No copy of the software may be distributed without this document;
  290.     and the contents of the document must not be altered.
  291.  
  292.     There is no warranty of any kind, and the copyright owner is not
  293.     liable for damages of any kind.  By using this free software, you
  294.     agree to this.
  295.  
  296.                       -------------------------------
  297.  
  298.                           The Cove Software Group
  299.                             Post Office Box 1072
  300.                             Columbia, MD  21044
  301.                                 410/992-9371
  302.                            CompuServe: 76703,2002
  303.  
  304.                      Program and documentation author:
  305.                            Christoper J. Dunford
  306.